Move documentation to inline comments: GtkBox

Fixes https://bugzilla.gnome.org/show_bug.cgi?id=611742

Signed-off-by: Javier Jardón <jjardon@gnome.org>

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index a9378ad349ac1c11dc5a945b92a34ec2f228a085..14c568ae7289e141f4e78042e76948be9543b0a5 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -1,3 +1,4 @@
+gtkbox.sgml
 gtkhbox.sgml
 gtkmessagedialog.sgml
 gtktesting.sgml

diff --git a/docs/reference/gtk/tmpl/gtkbox.sgml b/docs/reference/gtk/tmpl/gtkbox.sgml
deleted file mode 100644 (file)
index eb42208..0000000
--- a/docs/reference/gtk/tmpl/gtkbox.sgml
+++ /dev/null
@@ -1,291 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkBox
-
-<!-- ##### SECTION Short_Description ##### -->
-Base class for box containers
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-GtkBox is an abstract widget which encapsulates functionality for a
-particular kind of container, one that organizes a variable number of
-widgets into a rectangular area.  GtkBox has a number of derived
-classes, e.g. #GtkHBox and #GtkVBox.
-</para>
-<para>
-The rectangular area of a GtkBox is organized into either a single row
-or a single column of child widgets depending upon whether the box is
-of type #GtkHBox or #GtkVBox, respectively.  Thus, all children of a
-GtkBox are allocated one dimension in common, which is the height of a
-row, or the width of a column.
-</para>
-<para>
-GtkBox uses a notion of <emphasis>packing</emphasis>.  Packing refers to
-adding widgets with reference to a particular position in a
-#GtkContainer.  For a GtkBox, there are two reference positions: the
-<emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box.  
-For a #GtkVBox, the start is defined as the top of the box and the end is
-defined as the bottom.  For a #GtkHBox the start is defined as the
-left side and the end is defined as the right side.
-</para>
-<para>
-Use repeated calls to gtk_box_pack_start() to pack widgets into a
-GtkBox from start to end.  Use gtk_box_pack_end() to add widgets from
-end to start.  You may intersperse these calls and add widgets from
-both ends of the same GtkBox.
-</para>
-<para>
-Use gtk_box_pack_start_defaults() or gtk_box_pack_end_defaults()
-to pack widgets into a GtkBox if you do not need to specify the
-#GtkBox:expand, #GtkBox:fill, or #GtkBox:padding child properties 
-for the child to be added.
-</para>
-<para>
-Because GtkBox is a #GtkContainer, you may also use
-gtk_container_add() to insert widgets into the box, and they will be
-packed as if with gtk_box_pack_start_defaults().  Use
-gtk_container_remove() to remove widgets from the GtkBox.
-</para>
-<para>
-Use gtk_box_set_homogeneous() to specify whether or not all children
-of the GtkBox are forced to get the same amount of space.
-</para>
-<para>
-Use gtk_box_set_spacing() to determine how much space will be
-minimally placed between all children in the GtkBox.
-</para>
-<para>
-Use gtk_box_reorder_child() to move a GtkBox child to a different
-place in the box.
-</para>
-<para>
-Use gtk_box_set_child_packing() to reset the #GtkBox:expand, 
-#GtkBox:fill and #GtkBox:padding child properties.
-Use gtk_box_query_child_packing() to query these fields.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-<variablelist>
-
-<varlistentry>
-<term>#GtkHBox</term>
-<listitem><para>a derived class that organizes widgets into a row.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>#GtkVBox</term>
-<listitem><para>a derived class that organizes widgets into a column.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>#GtkFrame</term>
-<listitem><para>a #GtkWidget useful for drawing a border around a GtkBox.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>#GtkTable</term>
-<listitem><para>a #GtkContainer for organizing widgets into a grid,
-rather than independent rows or columns.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>#GtkLayout</term>
-<listitem><para>a #GtkContainer for organizing widgets into arbitrary
-layouts.</para></listitem>
-</varlistentry>
-
-</variablelist>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GtkBox ##### -->
-<para>
-The #GtkBox-struct describes an instance of GtkBox and contains the 
-following fields.  (These fields should be considered read-only. 
-They should never be set by an application.)
-</para>
-
-
-<!-- ##### ARG GtkBox:homogeneous ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkBox:spacing ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkBox:expand ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkBox:fill ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkBox:pack-type ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkBox:padding ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkBox:position ##### -->
-<para>
-
-</para>
-
-<!-- ##### STRUCT GtkBoxChild ##### -->
-<para>
-The #GtkBoxChild-struct holds a child widget of GtkBox and describes
-how the child is to be packed into the GtkBox.  Use
-gtk_box_query_child_packing() and gtk_box_set_child_packing() to query
-and reset the <structfield>padding</structfield>,
-<structfield>expand</structfield>, <structfield>fill</structfield>,
-and <structfield>pack</structfield> fields.
-</para>
-<para>
-#GtkBoxChild-struct contains the following fields.  (These fields
-should be considered read-only. They should never be directly set by an
-application.)
-</para>
-
-@widget: the child widget, packed into the GtkBox.
-@padding: the number of extra pixels to put between this child and its
-  neighbors, set when packed, zero by default.
-@expand: flag indicates whether extra space should be given to this
-  child. Any extra space given to the parent GtkBox is divided up 
-  among all children with this attribute set to %TRUE; set when packed, 
-  %TRUE by default.
-@fill: flag indicates whether any extra space given to this child due 
-  to its @expand attribute being set is actually allocated to the child, 
-  rather than being used as padding around the widget; set when packed, 
-  %TRUE by default.
-@pack: one of #GtkPackType indicating whether the child is packed with 
-  reference to the start (top/left) or end (bottom/right) of the GtkBox.
-@is_secondary: %TRUE if the child is secondary
-
-<!-- ##### FUNCTION gtk_box_pack_start ##### -->
-<para>
-
-</para>
-
-@box: 
-@child: 
-@expand: 
-@box
-@fill: 
-@padding: 
-
-
-<!-- ##### FUNCTION gtk_box_pack_end ##### -->
-<para>
-
-</para>
-
-@box: 
-@child: 
-@expand: 
-@fill: 
-@padding: 
-
-
-<!-- ##### FUNCTION gtk_box_pack_start_defaults ##### -->
-<para>
-
-</para>
-
-@box: 
-@widget: 
-
-
-<!-- ##### FUNCTION gtk_box_pack_end_defaults ##### -->
-<para>
-
-</para>
-
-@box: 
-@widget: 
-
-
-<!-- ##### FUNCTION gtk_box_get_homogeneous ##### -->
-<para>
-
-</para>
-
-@box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_box_set_homogeneous ##### -->
-<para>
-
-</para>
-
-@box: 
-@homogeneous: 
-
-
-<!-- ##### FUNCTION gtk_box_get_spacing ##### -->
-<para>
-
-</para>
-
-@box: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_box_set_spacing ##### -->
-<para>
-
-</para>
-
-@box: 
-@spacing: 
-
-
-<!-- ##### FUNCTION gtk_box_reorder_child ##### -->
-<para>
-
-</para>
-
-@box: 
-@child: 
-@position: 
-
-
-<!-- ##### FUNCTION gtk_box_query_child_packing ##### -->
-<para>
-
-</para>
-
-@box: 
-@child: 
-@expand: 
-@fill: 
-@padding: 
-@pack_type: 
-
-
-<!-- ##### FUNCTION gtk_box_set_child_packing ##### -->
-<para>
-
-</para>
-
-@box: 
-@child: 
-@expand: 
-@fill: 
-@padding: 
-@pack_type: 
-
-

diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index 1ebcbcf8e49daa8e7b6657814cec468ab79ea768..d9356f53e7a75d4fc3417615064289a4206c87f5 100644 (file)
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -24,6 +24,60 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  */
 
+/**
+ * SECTION:gtkbox
+ * @Short_description: Base class for box containers
+ * @Title: GtkBox
+ * @See_also:i #GtkHBox, #GtkVBox, #GtkFrame, #GtkTable, #GtkLayout
+ *
+ * GtkBox is an abstract widget which encapsulates functionality for a
+ * particular kind of container, one that organizes a variable number of
+ * widgets into a rectangular area.  GtkBox has a number of derived
+ * classes, e.g. #GtkHBox and #GtkVBox.
+ *
+ * The rectangular area of a GtkBox is organized into either a single row
+ * or a single column of child widgets depending upon whether the box is
+ * of type #GtkHBox or #GtkVBox, respectively.  Thus, all children of a
+ * GtkBox are allocated one dimension in common, which is the height of a
+ * row, or the width of a column.
+ *
+ * GtkBox uses a notion of <emphasis>packing</emphasis>.  Packing refers to
+ * adding widgets with reference to a particular position in a
+ * #GtkContainer.  For a GtkBox, there are two reference positions: the
+ * <emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box.
+ * For a #GtkVBox, the start is defined as the top of the box and the end is
+ * defined as the bottom.  For a #GtkHBox the start is defined as the
+ * left side and the end is defined as the right side.
+ *
+ * Use repeated calls to gtk_box_pack_start() to pack widgets into a
+ * GtkBox from start to end.  Use gtk_box_pack_end() to add widgets from
+ * end to start.  You may intersperse these calls and add widgets from
+ * both ends of the same GtkBox.
+ *
+ * Use gtk_box_pack_start_defaults() or gtk_box_pack_end_defaults()
+ * to pack widgets into a GtkBox if you do not need to specify the
+ * #GtkBox:expand, #GtkBox:fill, or #GtkBox:padding child properties
+ * for the child to be added.
+ *
+ * Because GtkBox is a #GtkContainer, you may also use
+ * gtk_container_add() to insert widgets into the box, and they will be
+ * packed as if with gtk_box_pack_start_defaults().  Use
+ * gtk_container_remove() to remove widgets from the GtkBox.
+ *
+ * Use gtk_box_set_homogeneous() to specify whether or not all children
+ * of the GtkBox are forced to get the same amount of space.
+ *
+ * Use gtk_box_set_spacing() to determine how much space will be
+ * minimally placed between all children in the GtkBox.
+ *
+ * Use gtk_box_reorder_child() to move a GtkBox child to a different
+ * place in the box.
+ *
+ * Use gtk_box_set_child_packing() to reset the #GtkBox:expand,
+ * #GtkBox:fill and #GtkBox:padding child properties.
+ * Use gtk_box_query_child_packing() to query these fields.
+ */
+
 #include "config.h"
 
 #include "gtkbox.h"

diff --git a/gtk/gtkbox.h b/gtk/gtkbox.h
index 914683b48e26bf6b7c913fd488ee1a595e02121b..038c3b1c3a1b35a6b095b8b1a28986973e0190b8 100644 (file)
--- a/gtk/gtkbox.h
+++ b/gtk/gtkbox.h
@@ -65,6 +65,28 @@ struct _GtkBoxClass
   GtkContainerClass parent_class;
 };
 
+/**
+ * GtkBoxChild:
+ * @widget: the child widget, packed into the GtkBox.
+ * @padding: the number of extra pixels to put between this child and its
+ *  neighbors, set when packed, zero by default.
+ * @expand: flag indicates whether extra space should be given to this child.
+ *  Any extra space given to the parent GtkBox is divided up among all children
+ *  with this attribute set to %TRUE; set when packed, %TRUE by default.
+ * @fill: flag indicates whether any extra space given to this child due to its
+ *  @expand attribute being set is actually allocated to the child, rather than
+ *  being used as padding around the widget; set when packed, %TRUE by default.
+ * @pack: one of #GtkPackType indicating whether the child is packed with
+ *  reference to the start (top/left) or end (bottom/right) of the GtkBox.
+ * @is_secondary: %TRUE if the child is secondary
+ *
+ * The #GtkBoxChild holds a child widget of #GtkBox and describes how the child
+ * is to be packed into the #GtkBox. All fields of this #GtkBoxChild should be
+ * considered read-only and they should never be set directly by an application.
+ * Use gtk_box_query_child_packing() and gtk_box_set_child_packing() to query
+ * and set the #GtkBoxChild.padding, #GtkBoxChild.expand, #GtkBoxChild.fill and
+ * #GtkBoxChild.pack fields.
+ */
 struct _GtkBoxChild
 {
   GtkWidget *widget;